Complete Linux

home *** CD-ROM | disk | FTP | other *** search

/ Complete Linux / Complete Linux.iso / docs / apps / database / ingres04.lzh / doc / unix / equel.doc < prev next >

Wrap

Text File | 1992-11-19 | 13.0 KB | 296 lines

EQUEL(UNIX) 3/14/79 EQUEL(UNIX) NAME equel - Embedded QUEL interface to C SYNOPSIS _e_q_u_e_l [ -_d ] [ -_f ] [ -_r ] file.q ... DESCRIPTION _E_q_u_e_l provides the user with a method of interfacing the general purpose programming language ``C'' with INGRES. It consists of the EQUEL pre-compiler and the EQUEL runtime li- brary. _C_o_m_p_i_l_a_t_i_o_n The precompiler is invoked with the statement: _e_q_u_e_l [<flags>] file1.q [<flags>] file2.q ... where file_n.q are the source input file names, which must end with ._q. The output is written to the file ``file_n.c''. As many files as wished may be specified. The flags that may be used are: -d Generate code to print source listing file name and line number when a run-time error occurs. This can be useful for debugging, but takes up process space. De- faults to off. -f Forces code to be on the same line in the output file as it is in the input file to ease interpreting C diag- nostic messages. EQUEL will usually try to get all C code lines in the output file on the same lines as they were in the input file. Sometimes it must break up queries into several lines to avoid C-preprocessor line overflows, possibly moving some C code ahead some lines. With the -_f flag specified this will never hap- pen and, though the line buffer may overflow, C lines will be on the right line. This is useful for finding the line in the source file that C error diagnostics on the output file refer to. -r Resets flags to default values. Used to supress other flags for some of the files in the argument list. The output files may than be compiled using the C compiler: _c_c file1.c file2.c ... -_l_q The -_l_q requests the use of the EQUEL object library. All EQUEL routines and globals begin with the characters "II", and so all globals variables and procedure names of the form II_x_x_x are reserved for use by EQUEL and should be avoided by EQUEL users. _B_a_s_i_c _S_y_n_t_a_x EQUEL commands are indicated by lines which begin with a double pound sign (``##''). Other lines are simply copied as is. All normal INGRES commands may be used in EQUEL and have the same effect as if invoked through the interactive terminal monitor. Only retrieve commands with no result re- lation specified have a different syntax and meaning. The format of retrieve without a result relation is modified to: ## retrieve (C-variable = a_fcn { , C-variable = a_fcn } ) optionally followed (immediately) by: ## [ _w_h_e_r_e _q_u_a_l ] ## { /* C-code */ ## } This statement causes the ``C-code'' to be executed once for each tuple retrieved, with the ``C-variable''s set appropri- ately. Numeric values of any type are converted as neces- sary. No conversion is done between numeric and character values. (The normal INGRES _a_s_c_i_i function may be used for this purpose.) Also, the following EQUEL commands are permitted. ## _i_n_g_r_e_s [ingres flags] data_base_name This command starts INGRES running, and directs all dynamically following queries to the database _d_a_t_a__b_a_s_e__n_a_m_e. It is a run-time error to execute this command twice without an intervening ``## exit'', as well as to issue queries while an ``## ingres'' state- ment is not in effect. Each flag should be enclosed in quotes to avoid confusion in the EQUEL parser: ## ingres "-f4f10.2" "-i212" demo ## _e_x_i_t Exit simply exits from INGRES. It is equivalent to the _\_q command to the teletype monitor. _P_a_r_a_m_e_t_r_i_z_e_d _Q_u_e_l _S_t_a_t_e_m_e_n_t_s Quel statements with target lists may be ``parametrized''. This is indicated by preceding the statement with the key- word ``param''. The target list of a parametrized statement has the form: ( _t_l__v_a_r, _a_r_g_v ) where _t_l__v_a_r is taken to be a string pointer at execution time (it may be a string constant) and interpreted as fol- lows. For any parametrized EQUEL statement except a re- trieve without a result relation (no ``into rel'') (i.e. ap- pend, copy, create, replace, retrieve into) the string _t_l__v_a_r is taken to be a regular target list except that wherever a `%' appears a valid INGRES type (f4, f8, i2, i4, c) is expected to follow. Each of these is replaced by the value of the corresponding entry into _a_r_g_v (starting at 0) which is interpreted to be a pointer to a variable of the type indicated by the `%' sequence. Neither _a_r_g_v nor the variables which it points to need be declared to EQUEL. For example: char *argv[10]; argv[0] = &double_var; argv[1] = &int_var; ## param append to rel ## ("dom1 = %f8, dom2 = %i2", argv) ## /* to escape the "%<ingres_type>" mechanism use "%%" */ ## /* This places a single `%' in the string. */ On a retrieve to C-variables, within _t_l__v_a_r, instead of the C-variable to retrieve into, the same `%' escape sequences are used to denote the type of the corresponding argv entry into which the value will be retrieved. The qualification of any query may be replaced by a string valued variable, whose contents is interpreted at run time as the text of the qualification. The _c_o_p_y statement may also be parametrized. The form of the parametrized _c_o_p_y is analogous to the other parametrized statements: the target list may be parametrized in the same manner as the _a_p_p_e_n_d statements, and furthermore, the _f_r_o_m/_i_n_t_o keyword may be replaced by a string valued vari- able whose content at run time should be _i_n_t_o or _f_r_o_m. _D_e_c_l_a_r_a_t_i_o_n_s Any valid C variable declaration on a line beginning with a ``##'' declares a C-variable that may be used in an EQUEL statement and as a normal variable. All variables must be declared before being used. Anywhere a constant may appear in an INGRES command, a C-variable may appear. The value of the C-variable is substituted at execution time. Neither nested structures nor variables of type _c_h_a_r (as op- posed to pointer to char or array of char) are allowed. Furthermore, there are two restrictions in the way variables are referenced within EQUEL statements. All variable usages must be dereferenced and/or subscripted (for arrays and pointers), or selected (for structure variables) to yield lvalues (scalar values). _C_h_a_r variables are used by EQUEL as a means to use _s_t_r_i_n_g_s. Therefore when using a _c_h_a_r ar- ray or pointer it must be dereferenced only to a ``_c_h_a_r *''. Also, variables may not have parentheses in their refer- ences. For example: ## struct xxx ## { int i; ## int *ip; ## } **struct_var; /* not allowed */ ## delete p where p.ifield = *(*struct_var)->ip /* allowed */ ## delete p where p.ifield = *struct_var[0]->ip C variables declared to EQUEL have either global or local scope. Their scope is local if their declaration is within a free (not bound to a retrieve) block declared to EQUEL. For example: /* globals scope variable */ ## int Gint; func(i) int i; ## { /* local scope variable */ ## int *gintp; ... ## } If a variable of one of the char types is used almost any- where in an EQUEL statement the content of that variable is used at run time. For example: ## char *dbname[MAXDATABASES + 1]; int current_db; dbname[current_db] = "demo"; ## ingres dbname[current_db] will cause INGRES to be invoked with data base ``demo''. However, if a variable's name is to be used as a constant, then the non-referencing operator `#' should be used. For example: ## char *demo; demo = "my_database"; /* ingres -d my_database */ ## ingres "-d" demo /* ingres -d demo */ ## ingres "-d" #demo The C-preprocessor's #include feature may be used on files containing equel statements and declarations if these files are named _a_n_y_t_h_i_n_g._q._h. An EQUEL processed version of the file, which will be #included by the C-preprocessor, is left in _a_n_y_t_h_i_n_g._c._h. _E_r_r_o_r_s _a_n_d _I_n_t_e_r_r_u_p_t_s INGRES and run-time EQUEL errors cause the routine _I_I_e_r_r_o_r to be called, with the error number and the parameters to the error in an array of string pointers as in a C language main routine. The error message will be looked up and printed. before printing the error message, the routine (*IIprint_err)() is called with the error number that ocurred as its single argument. The error message corresponding to the error number returned by (*IIprint_err)() will be printed. Printing will be supressed if (*IIprint_err)() returns 0. IIprint_err may be reassigned to, and is useful for programs which map INGRES errors into their own error messages. In addition, if the ``-_d'' flag was set the file name and line number of the er- ror will be printed. The user may write an IIerror routine to do other tasks as long as the setting of IIerrflag is not modified as this is used to exit retrieves correctly. Interrupts are caught by equel if they are not being ig- nored. This insures that the rest of INGRES is in sync with the EQUEL process. There is a function pointer, IIinter- rupt, which points to a function to call after the interrupt is caught. The user may use this to service the interrupt. It is initialized to "exit()" and is called with -1 as its argument. For example: extern int (*IIinterrupt)(); extern reset(); setexit(); IIinterrupt = reset; mainloop(); To ignore interrupts, signal() should be called before the ## ingres satatement is executed. FILES .../files/error8_* Can be used by the user to decipher INGRES error numbers. .../lib/libq.a Run time library. SEE ALSO .../doc/other/equeltut.q, C reference manual, ingres(UNIX), quel(QUEL) BUGS The C-code embedded in the tuple-by-tuple retrieve operation may not contain additional QUEL statements or recursive in- vocations of INGRES. There is no way to specify an _i_1 format C-variable. Includes of an equel file within a parameterized target list, or within a C variable's array subscription brackets, isn't done correctly.